home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / IIGS / TN.IIGS.091 < prev    next >
Encoding:
Text File  |  1991-06-28  |  10.4 KB  |  233 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6.  
  7. Apple IIgs
  8. #91:         The Wonderful World of Universal Access
  9.  
  10. Revised by:  Ron Lichty and Dave Lyons                              July 1991
  11. Written by:  Don J. Brady & Matt Deatherage                    September 1990  
  12.       
  13. This Technical Note discusses how your applications can be compatible with 
  14. Universal Access software.
  15.  
  16. Changes since September 1990:  Changed name of "Keyboard Mouse" to "Mouse 
  17. Keys." Revised to include a discussion of drawing custom items in dialogs.
  18. ____________________________________________________________________________
  19.  
  20.  
  21. What's "Universal Access?"
  22.  
  23. Universal Access is the name given to software components designed to make 
  24. Apple computers (in this case, the Apple IIgs) more accessible to people who 
  25. might have difficulty using them.  The Apple IIgs is very dependent on 
  26. graphic objects, a keyboard and mouse; not all people can use these things 
  27. very easily.
  28.  
  29. There are several components to Apple's Universal Access software:
  30.  
  31. o    CloseView.  CloseView magnifies the Apple IIgs screen so that it's more
  32.      easily seen by those with visual impairments.  The hardware screen 
  33.      contains a magnification from two to twelve times as large as the "real" 
  34.      32K Super Hi-Res graphics screen.
  35.  
  36. o    Video Keyboard.  Video Keyboard is a New Desk Accessory that emulates a 
  37.      keyboard.  A picture of a keyboard appears on the screen; a mouse-down 
  38.      event in any "key" makes Video Keyboard post a key-down event, so you 
  39.      can use a pointing device as a keyboard.  ADB hardware is available to 
  40.      allow people to use head gear or other devices instead of mice; Video 
  41.      Keyboard lets these same devices replace the keyboard as well.
  42.  
  43. o    Easy Access.  Easy Access comes in two parts: Sticky Keys and Mouse 
  44.      Keys.  Sticky Keys makes the keyboard easier to use for those who have 
  45.      trouble pressing more than one key at a time; while Sticky Keys is 
  46.      activated, modifier keys may be released and still apply to the next 
  47.      keystroke.  Mouse Keys allows the numeric keypad to be used as a mouse 
  48.      substitute.  Sticky Keys and Mouse Keys are included in all ROM 03 Apple 
  49.      IIgs computers.  The software versions allow all Apple IIGS computers to 
  50.      provide these functions, and provide additional icon feedback (in the 
  51.      upper right menu bar) for Sticky Keys.
  52.  
  53.  
  54.  
  55. How It Works (Access Nothing and Checks For Free)
  56.  
  57. Universal Access generally works by replacing Apple IIgs toolbox functions.  
  58. For example, CloseView patches QuickDraw so you do not draw to the actual 
  59. screen, but to another buffer that CloseView can then magnify.  Video 
  60. Keyboard patches the Window Manager so that its keyboard window is always 
  61. frontmost and fully visible (and accessible).  Easy Access uses the ADB tools 
  62. and the Event Manager to alter the way the hardware responds.
  63.  
  64. Since Universal Access changes the way the tools behave, your applications do 
  65. not have to work very hard to be accessible to a broad range of physically 
  66. challenged people.  Just by following the rules, you have an accessible 
  67. application.  There are, however, a few guidelines you should keep in mind 
  68. when designing your programs to make them as accessible as they can be.
  69.  
  70.  
  71. Universal Access Compatibility Guidelines
  72.  
  73. o    Try to avoid using modal dialogs.  Not only do lots of modal dialogs 
  74.      make for a cumbersome interface for everyone, they are especially 
  75.      annoying to those who have to move the mouse to a lot of OK buttons.  
  76.      More importantly, users cannot open NDAs like Video Keyboard while modal 
  77.      dialogs are frontmost.
  78.  
  79.      Video Keyboard can also be dragged in front of modal dialogs. If you are 
  80.      in the habit of using QuickDraw calls to draw items in Dialog Manager 
  81.      modal dialogs instead of creating custom dialog userItems, Video 
  82.      Keyboard users can drag the keyboard window in front of your dialog and 
  83.      erase the items (since the only items redrawn are those redrawn by the 
  84.      Dialog Manager's update routine).    You can easily test this in all of 
  85.      your dialogs by obscuring each dialog with the Video Keyboard window a 
  86.      piece at a time, then moving Video Keyboard away, to be sure that all 
  87.      areas are completely redrawn.
  88.  
  89.      Let's say, for example, that you have a custom text item that changes
  90.      between invocations of the same modal dialog.  You might choose to draw 
  91.      the text yourself with LETextBox2 after creating the dialog with 
  92.      GetNewModalDialog but before letting the Dialog Manager handle events 
  93.      with ModalDialog:
  94.  
  95.     phx                ; port: hi word from GetNewModalDialog
  96.     pha                ; port: lo word from GetNewModalDialog
  97.     _SetPort
  98.  
  99.     lda OurText+2            ; pointer to text to draw in modal dialog
  100.     pha
  101.     lda OurText
  102.     pha
  103.     lda OurTextLength        ; Text length
  104.     pha
  105.     pea OurTextRect>>16        ; Text rectangle
  106.     pea OurTextRect
  107.     pea 0002            ; Text justification (2 = fill)
  108.     _LETextBox2
  109.  
  110.     To be Universal Access-friendly, you would, instead, implement a userItem 
  111.     routine like the following:
  112.  
  113.     ; . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  114.     DrawDialogText
  115.     ;
  116.     ; DrawDialogText draws text pointed to by OurText into the Dialog.
  117.     ; This userItem routine is called only by the Dialog Manager, 
  118.     ;   when it's implementing/updating the dialog.
  119.     ; . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
  120.  
  121.         lda >OurText+2        ; pointer to text to draw in modal dialog
  122.         pha
  123.         lda >OurText            ; (long addressing: data bank unknown)
  124.         pha
  125.         lda >OurTextLength        ; Text length
  126.         pha
  127.         pea OurTextRect>>16         ; Text rectangle
  128.         pea OurTextRect
  129.         pea 0002            ; Text justification (2 = fill)
  130.         _LETextBox2
  131.  
  132.         lda 1,s            ; get return address
  133.         sta 7,s            ; move to proper location
  134.         lda 2,s            ;  above input parameters
  135.         sta 8,s
  136.     
  137.         pla                ; move stack pointer up
  138.         pla                ;  to new return address location
  139.         pla
  140.         rtl
  141.  
  142.     It will be called as a result of adding a template item like the 
  143.     following to the dialog template (note use of Item Value for the text 
  144.     length, since template Value fields are not used by userItems):
  145.  
  146.     TextTemplate  dc.w 3                     ; ID
  147.     OurTextRect   dc.w TTop,TLeft,TBottom,TRight
  148.                   dc.w UserItem+ItemDisable     ; Type
  149.                   dc.l DrawDialogText        ; Pointer to our userItem 
  150.                                              ; routine
  151.     OurTextLength ds.w 1                ; Text length (cheap place to put it)
  152.                   dc.w 0000             ; Item flag
  153.                   dc.l 00000000              ; Item color
  154.  
  155.     Note that this is a simple example of a custom item routine; if you 
  156.     really had custom text that changed from invocation to invocation, you 
  157.     could use the existing Dialog Manager ParamText and longStatText2 item 
  158.     mechanisms.
  159.  
  160. o    Use the Event Manager routines for event information.  Do not access any 
  161.      hardware directly or use the lower-level Miscellaneous Tools routines 
  162.      for user event information--you steal that information from Universal 
  163.      Access.  For example, use the Event Manager routine GetMouse to find the 
  164.      mouse location.  Do not use ReadMouse or you steal mouse movement 
  165.      information from Universal Access.
  166.  
  167. o    Call GetNextEvent or TaskMaster often.  Long delays between calls do not 
  168.      let NDAs like Video Keyboard get events.  If you cannot make these 
  169.      calls, at least call SystemTask.
  170.  
  171. o    Do not assume that the hardware location of the screen is $E12000.  
  172.      Universal Access components that manipulate the entire screen (like 
  173.      CloseView) move the virtual screen so the hardware can be used for the 
  174.      magnified screen image.
  175.  
  176.      To find the screen location, look at the ptrToPixImage field in a 
  177.      grafPort after calling OpenPort (or in your window's window record after 
  178.      NewWindow).  The image pointer gives the correct location of the screen.
  179.  
  180.      Assuming the current port is on screen, the following code finds the 
  181.      ptrToPixImage value:
  182.  
  183.         pha
  184.         pha    ;made space for port pointer
  185.         _GetPort
  186.         phd    ;save direct page location
  187.         tsc
  188.         tcd    ;port pointer is now at 3..6 on direct page
  189.         ldy #4    ;offset to high word of ptrToPixImage
  190.         lda [3],y    ;got high word
  191.         tax    ;  in X
  192.         ldy #2    ;offset to low word of ptrToPixImage
  193.         lda [3],y    ;got low word
  194.         tay    ;  in Y
  195.         pld    ;restored direct page location
  196.         pla
  197.         pla    ;removed port pointer
  198.  
  199.      The X and Y registers now contain the base address of the screen.
  200.  
  201.  
  202. o    Do not assume things about being the frontmost window.  Even if 
  203.      FrontWindow says you have the frontmost window, your visRgn may have 
  204.      pieces missing.  For example, the title bar of your window may be 
  205.      partially under the menu bar.  Or there may be a floating "windoid" 
  206.      (like Video Keyboard's window) over part of your window.
  207.  
  208.      For these reasons you should not draw directly to the screen without 
  209.      first examining your window's visRgn.  Do not just check for 
  210.      rectangularity--your visRgn could be rectangular and parts of your 
  211.      window still be obscured.  If you use QuickDraw for all your drawing, 
  212.      QuickDraw automatically clips drawing activity to be entirely within the 
  213.      visRgn, so this is not a problem.
  214.  
  215. o    Don't access QuickDraw data directly; use QuickDraw routines instead.  
  216.      For example, to access SCB data, use the QuickDraw routines GetSCB and 
  217.      SetSCB instead of reading the hardware at $E19D00.  CloseView may have 
  218.      those SCBs changed to reflect a magnified portion of the screen.  Also 
  219.      use GetColorEntry, SetColorEntry, GetColorTable, and SetColorTable.  
  220.      Don't access the hardware directly.
  221.  
  222. o    Try to allocate memory after starting the tools.  If you want to 
  223.      allocate memory before starting tools, do not use special memory.  (Set 
  224.      the attrNoSpec bit in the attributes.)
  225.  
  226.  
  227. Further Reference
  228. _____________________________________________________________________________
  229.   o  Apple IIgs Toolbox Reference
  230.   o  Apple IIgs Firmware Reference 
  231.   o  Apple II Video Overlay Card Development Kit (APDA)
  232.  
  233.